Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>

Moves the scope, exclusion-category reasoning, regulatory framing
(MiCA EMT / MAS SCS / FSB / BIS), and trust model out of the
IB20Stablecoin, ITokenFactory, and ISO4217 natspec into a single
canonical docs/iso4217-filter.md. The new file presents inclusion /
exclusion as a scannable table and totals ~26 lines.

Natspec now stays at the API-contract layer: what each function
does, what reverts, with one-line pointers to docs/ for the deeper
context. Per-entry rationale in ISO4217.excludedAt stays inline
since it answers "why isn't X on the list?" at the exact location
a reader would ask.

Net: -217 natspec lines, +26 docs lines. IB20Stablecoin.sol is now
20 lines total.

Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>

…and to full problem/solution/risks

Restructures the docs file into a four-section flow that's
self-describing on its own: problem statement (why constrain
currency at all), solution (ISO 4217 fiat subset), complete
specification (the inclusion/exclusion table), and risks +
mitigations (PAXG-class commodities go to Security; DAI-class
crypto-collateralized still fit; basket/algorithmic have no home;
naming friction with industry terminology is anchored in MiCA / MAS
precedent; trust model is consumer-layered).

Moves the file from docs/iso4217-filter.md to
docs/b20/stablecoin/currency-validation.md so the docs taxonomy
mirrors the interface hierarchy (B20 / B20Stablecoin / concept).

Updates all natspec links to the new path and trims two more
small natspec sprawls — the X-prefix inline comment and the
isValidFiatCode @notice — that duplicated content now in docs.

Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>

MockTokenFactory's 7-line ISO-4217 explainer collapses to one line
pointing at docs/. The five currency tests in createToken.t.sol
each drop to a 2-line @notice + @dev docblock; the section header
collapses from a 12-line preamble to a single pointer comment.

Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>

Tests with arguments are fuzzed by default in Foundry; the suite
convention is test_{function}_{condition}_{case} regardless of
whether the body uses fuzz inputs.

Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>

Replaces the per-comparison `keccak256("AED")` form with a block of
named `bytes3 private constant` declarations at the top of the
library, and a comparison chain that reads `c == AED || c == AFN ||
...`. The canonical 155-entry list is now visible as data, easier
to scan against ISO 4217, and easier to audit for additions and
removals.

Honest tradeoff: per-call gas is ~2× higher than the keccak chain
(the Solidity optimizer was already constant-folding the keccak
literals, so the old version was paying ~1 keccak on the input
plus 155 PUSH32 EQ; the new version pays no keccak but ~155 PUSH3
EQ with additional control-flow overhead). Impact is mock-test
runtime only; the Rust precompile will hash to O(1) regardless.

A first-byte-dispatch optimization (`if (first == "U") return c ==
USD || ...`) would bring gas below the keccak version while keeping
the readability win; deferred until reviewer signs off on the
readability direction.

Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>

Wraps the bytes3 comparison chain in an outer `if (first == "X")`
dispatch on the input's first byte, so each call evaluates at most
one letter bucket instead of all 26. Worst-case ≈ 16 word-equality
comparisons (S bucket, 15 entries) plus a few first-byte branches,
vs ≈ 155 for a flat chain.

Per-call gas (micro-bench, 100 calls each):
  - keccak (original):  4.2k / call
  - bytes3 flat:        7.9k / call
  - this commit:        1.4k / call  (~3× faster than keccak)

Adds an @dev natspec on `isValidFiatCode` documenting the O(1)
amortized characteristic and the worst-case bucket size.

Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>

Sorts entries within each first-byte bucket so the highest-volume
codes short-circuit first. USD/EUR/JPY/GBP/CHF/CAD/AUD/SEK/NOK/NZD
(G10) lead their respective buckets, with CNY, INR, MXN, BRL, etc.
following close behind. Also reorders the outer letter-dispatch so
the buckets containing the G10 and top-FX currencies are checked
first (U/E/J/G/C/A/N/S/I/M/T/P/K/B/H/R/D/X/Z/V/L), keeping
single-entry buckets at the end.

Per-call gas (micro-bench, 100 calls each):
  - USD: ~370 gas  (was 1.4k; ~11× the original keccak chain's 4.2k)
  - EUR: ~400 gas
  - JPY: ~430 gas
  - ZWG (late): ~1.3k
  - ZZZ (miss): ~1.3k

Mean for real-world stablecoin traffic — overwhelmingly USD with
EUR a distant second — is effectively two comparisons (first-byte
+ first match), per the power-law observation that drove the sort.

Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>

The library is consumed only by the mock factory and test fuzzers,
so it doesn't belong under src/ — moving to test/lib/ alongside
the other mock-supporting code keeps the src/ surface focused on
the interfaces consumers actually import. The src/utils/ directory
is removed (it had no other entries).

Also appends a "Supported currencies" table to the docs page
listing all 155 allowlist codes alphabetically with currency name
and region/issuer. Useful as a self-contained reference so readers
don't have to map ISO 4217 codes to currencies themselves.

Updates the docs-file path link from src/utils/ to test/lib/ and
the natspec import paths in MockTokenFactory and createToken.t.sol.

Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>

Captures the five validation approaches surfaced during design (no
validation, format-only, full ISO 4217, narrow ISO 4217 fiat, off-
chain registry) with a one-line rationale for why each non-chosen
option was set aside. Marks the chosen approach inline so the
decision is visible without forcing readers to cross-reference the
solution section.

Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>

Bolds the option title, moves the description underneath with a
`<br>` separator, and splits the per-option rationale into
bulleted Pros and Cons columns. Easier to scan; trade-offs land on
both sides of the line rather than only as a single "why not"
sentence.

Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>

… row

Adds manual `<br>` breaks within each Option-column description so
the column stops sprawling and the Pros/Cons columns get balanced
width. Removes the off-chain registry row — it's a non-option (no
on-chain validation defeats the whole purpose).

Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>